Format of Fields

Instructions for Twistory 2.1

Fields

All of the information in a place, person, event, sphere, or menu-item record is in the form of fields, which have a common format. They all begin with a field identifier between the characters < and >. The following table summarises them. Some fields, like the name, <n>, can be used with different types of records. Others can only be used with one type. The letters c, p, e, s and i indicate which records they may be used with.

Following the table, the various fields are explained. The syntax line describes the format of the data which follows the field identifier. Spaces on either end of field data are ignored.

Mark-up Description Use Syntax Remarks

<n> name c p e s i string See note on names.

<aka> alias or alternate name c p string

<reg> region (name of place) c s string This specifies the next larger region in geographical hierarchy.

<l> geographic location c s georef

<rad> radius (in km) c s integer The size of an area is used by Twistory to suppress map legends at small scales. Few countries are exactly circular, so how is radius defined? It should be a circle that encompasses "most" of a region. In any event, the radius should extend at least half-way from the centre of the region to the centre of the farthest sub-region; else Twistory will generate an alert.

<rep> replaced area c string This field specifies an older area name (whose definition must precede this one's) which is temporally superceded by this area's name.

<col> colour c s i colour The colour is used in time-line bars.

<wat> body of water c n/a boolean mark-up (no field following)

<nat> nationality c p string For a place, this is the national adjective, i.e. the name for a person who lives there. For a person, this string should match the <nat> field of some region.

<c> place p e string This is used to specify the name of the place where a person lived or an event happened.

<info> additional information p e string Further information, which appears in "Info" windows; this should be in sentence form. See note on hyperlinks.

<ref> reference p e string This is used to specify the books or other sources from which the information came.

<pict> picture p e file name A reference to a picture. Up to one picture may be associated with a person or event. It will open in a separate window when the "Info" window is opened.

<cap> picture caption p e string A phrase may optionally be associated with the picture in the <pict> field.

<sur> surname p string This is optional for a person. Use it if necessary to override the short forms that Twistory uses at large time scales.

<fem> female p i n/a boolean mark-up (no field following)

<o> occupation p i string This should match an occupation defined in a menu item.

<b> date of birth p date

<d> date of death p date

<gen> age of parent at birth p integer The age of a parent at the person's birth. This can be used instead of a birth year when it is more convenient. See note on order.

<tr> date of translation p date This is used in preference to <d> in a case where the person did not die, but was taken up.

<fa> father's name p string See note on order.

<mo> mother's name p string See note on order.

<ac>, <ap>, <pow>, <el> date of coming to power p date Use <ac> for accession, <ap> for appointment, <pow> for taking power, and <el> for election to office. Twistory treats these similarly.

<ab>, <depo>, <ret> date of leaving power p date Use <ab> for abdication, <depo> for being deposed, and <ret> for retirement from office. Twistory also treats these in a similar manner. It is not necessary to specify this date when it coincides with death.

<dep>, <arr>, <mov> dates of depature and arrival p e date Use these, along with <c>, to describe the travels of a person, or the itinerary of an event. The <mov> field specifies a transition between two places where the time spent travelling is not significant. Using <mov> has the same effect as using both <dep> and <arr> with the same dates.

<d> date e s date The date of an event, or the start date for an extended event. (This field has the same abbreviation as date of death, above, but is parsed correctly in the context of an event or sphere record.)

<e> ending date e s date

<t> event type e i string For a menu item, this is the name of the type being defined, e.g. "battle." For an event, this field should match a defined event type.

<p> associated person e string For an event, this field should hold the name of a person, such as the author or inventor, with whom the event is most closely associated. The name of the person should also appear in the <info> field with a hyperlink, since it will not otherwise appear in the "info" window (as it did with the former <au> field).

<poly> polygon s file name

<icon> icon for occupation or event type i string See note on icons.

<off> menu item initially unselected i n/a boolean mark-up (no field following)

Mark-up	Description	Use	Syntax	Remarks
<n>	name	c p e s i	string	See note on names.
<aka>	alias or alternate name	c p	string
<reg>	region (name of place)	c s	string	This specifies the next larger region in geographical hierarchy.
<l>	geographic location	c s	georef
<rad>	radius (in km)	c s	integer	The size of an area is used by Twistory to suppress map legends at small scales. Few countries are exactly circular, so how is radius defined? It should be a circle that encompasses "most" of a region. In any event, the radius should extend at least half-way from the centre of the region to the centre of the farthest sub-region; else Twistory will generate an alert.
<rep>	replaced area	c	string	This field specifies an older area name (whose definition must precede this one's) which is temporally superceded by this area's name.
<col>	colour	c s i	colour	The colour is used in time-line bars.
<wat>	body of water	c	n/a	boolean mark-up (no field following)
<nat>	nationality	c p	string	For a place, this is the national adjective, i.e. the name for a person who lives there. For a person, this string should match the <nat> field of some region.
<c>	place	p e	string	This is used to specify the name of the place where a person lived or an event happened.
<info>	additional information	p e	string	Further information, which appears in "Info" windows; this should be in sentence form. See note on hyperlinks.
<ref>	reference	p e	string	This is used to specify the books or other sources from which the information came.
<pict>	picture	p e	file name	A reference to a picture. Up to one picture may be associated with a person or event. It will open in a separate window when the "Info" window is opened.
<cap>	picture caption	p e	string	A phrase may optionally be associated with the picture in the <pict> field.
<sur>	surname	p	string	This is optional for a person. Use it if necessary to override the short forms that Twistory uses at large time scales.
<fem>	female	p i	n/a	boolean mark-up (no field following)
<o>	occupation	p i	string	This should match an occupation defined in a menu item.
<b>	date of birth	p	date
<d>	date of death	p	date
<gen>	age of parent at birth	p	integer	The age of a parent at the person's birth. This can be used instead of a birth year when it is more convenient. See note on order.
<tr>	date of translation	p	date	This is used in preference to <d> in a case where the person did not die, but was taken up.
<fa>	father's name	p	string	See note on order.
<mo>	mother's name	p	string	See note on order.
<ac>, <ap>, <pow>, <el>	date of coming to power	p	date	Use <ac> for accession, <ap> for appointment, <pow> for taking power, and <el> for election to office. Twistory treats these similarly.
<ab>, <depo>, <ret>	date of leaving power	p	date	Use <ab> for abdication, <depo> for being deposed, and <ret> for retirement from office. Twistory also treats these in a similar manner. It is not necessary to specify this date when it coincides with death.
<dep>, <arr>, <mov>	dates of depature and arrival	p e	date	Use these, along with <c>, to describe the travels of a person, or the itinerary of an event. The <mov> field specifies a transition between two places where the time spent travelling is not significant. Using <mov> has the same effect as using both <dep> and <arr> with the same dates.
<d>	date	e s	date	The date of an event, or the start date for an extended event. (This field has the same abbreviation as date of death, above, but is parsed correctly in the context of an event or sphere record.)
<e>	ending date	e s	date
<t>	event type	e i	string	For a menu item, this is the name of the type being defined, e.g. "battle." For an event, this field should match a defined event type.
<p>	associated person	e	string	For an event, this field should hold the name of a person, such as the author or inventor, with whom the event is most closely associated. The name of the person should also appear in the <info> field with a hyperlink, since it will not otherwise appear in the "info" window (as it did with the former <au> field).
<poly>	polygon	s	file name
<icon>	icon for occupation or event type	i	string	See note on icons.
<off>	menu item initially unselected	i	n/a	boolean mark-up (no field following)